Pascal pretty - printing : an example of " preprocessing w i t h TEX

Pretty-printing a piece of Pascal code with TEX is often done via an external preprocessor. Actually, the job can be done entirely in TEX; this paper introduces PPP, a Pascal pretty-printer environment that allows you to typeset Pascal code by simply typing \Pascal {Pascal code) \endpascal. The same approach of "preprocessing w i t h TEX" namely two-token tail-recursion around a \FIND-like macro can be applied easily and successfully to numerous other situations. Introduction This solution is portable (it can run wherever TEX A pretty-printed piece of computer code is a st&ing example of how the typeset form can reveal the contents of a document. Because the contents are rigorously structured, an equally rigorous typeset form helps the reader understand the logic behind the code, recognize constructs that are similar, and differentiate those that are not. Not surprisingly, many programming environments nowadays provide programmers with a pretty-printed representation of the code they are working on. In the typesetting world, TEX seems an obvious candidate for a pretty-printing environment, thanks to its programming capabilities and its focus on logical rather than visual design. The current standard for typesetting Pascal code with TEX seems to be TGRIND, a preprocessor running under UNIX. Useful as it may be, TGRIND also has limitations. While it can recognize reserved words, it does little to reflect logical content with indentation. In fact, it indents by replacing spaces in the original file by fixed \ h s k i p's. Of course, it can be used on the result produced by an ASCII-oriented pretty-printer, which generates the right number of spaces according to logical contents. Alternatives to TGRIND are either to develop a dedicated preprocessor a computer program that takes a piece of Pascal code as input and produces a TEX source He as output-or to do the equivalent of the preprocessing work within TEX. The first solution is likely to be faster, hence more convenient for long listings, but requires an intermehate step and is less portable. The second, by contrast, is rather slow, but also quite convenient: pieces of Pascal code can be inserted (\input) as is in a TEX document, or written directly within TEX. m s ) , requires no intermediate step (it does its j i b whenever the document is typeset), and, like other sets of macros, can be fine-tuned or customized to personal preferences while maintaining good logical design. This article describes briefly the main features and underlying principles of PPP, a Pascal prettyprinting environment that was developed for typesetting (short) pieces of Pascal code in engineering textbooks. It then discusses how to use the same principles of "preprocessing withn TEX" to quickly build other sets of macros that gobble up characters and replace them with other tokens, to be further processed by TEX. The complete PPP macro package will soon be found on the CTAN archives. Of course, there are other ways of tackling the issue, with either a broader or a narrower scope. Structured software documentation at large can benefit from the literate programming approach and corresponding tools, with TEX or fiT~X as a formatter a discussion beyond the scope of this paper. Occasional short pieces of code, on the other hand, can also be typeset verbatim or with a few ad hoc macros, for example a simple tabbing environment, as shown by Don Knuth (1984, page 234). For additional references, see also the compilation work of Piet van Oostrum (1991). Main features of macros Basic use. PPP works transparently; you do not need to know much to run it. After \i nputing the macros in your source, all you do is write \Pascal (Pascal code) \endpascal 302 TUGboat, Volume 15 (1994), No. 3 -Proceedings of the 1994 Annual Meeting Pascal pretty-printing in p la in . t ex or \begi n{Pascal } ( Pascal code) \end{Pascal } in LATEX, where (Pascal code) can be an \ input command. The PPP package then pretty-prints the corresponding Pascal code; by default, it typesets reserved words in boldface; indents the structure according to syntax (identifying such constructs as begin . . . end and if . . . then.. . else . . .;); typesets string literals in monospaced (\tt) font; considers comments to be TEX code and typesets them accordingly. The Appendix illustrates these features. Customization. PPP is de&cated to Pascal. Though you can use the same underlying principles (see next section) in other contexts, you cannot easily modify PPP to pretty-print very different programming languages. There is, however, room for customizing the pretty-printing, and this at several levels. At a high level, you can use the token registers \everypascal, \ everys t r i ng, as well as \everycomment to add formatting commands to be applied, respectively, to the entire Pascal code, to the Pascal string literals, and to the Pascal comments. If you want your whole Pascal code to be in nine-point roman, for example, you can say \everypascal {\ninerm \basel i neski p=lOpt(etc.) } If you would rather use '(' and ')' instead of '[' and ' I ' as TEX grouping delirniters in Pascal comments, YOU can say Comments. Recognizing comments as TEX code is \everycomment{\catcode'\(=l \catcode'\)=2} particularly powerful: side by side with a rather Similarly, if you wish to reproduce the comments strict typeset design for the program itself, comverbatim rather than consider them as TEX code, ments can be typeset with all of T@'s flexibility and you can say power. Besides for adding explanatory comments \everycomment{\verbatimcomments} to the program, t h s possibility can be used to fine-tune the layout. Extra vertical space and page At an intermediate level, you can add reserved breaks can be added in this way. Such comments words by d e h g a macro with the same name as can even be made ynvisiblen, so no empty pair of the reserved word prefixed with p@. If you want comment delimiters shows on the ~ a a e . the Pascal identifier f o o to be displayed in italics in ., Accessing TEX within comments suffers a notable exception, though. Pascal comments can be delimited with braces, but Pascal compilers do not match braces: the first opening brace opens the comment and the first closing brace closes the comment, irrespective of how many other opening braces are in between. As a consequence, braces cannot be used for delimiting TEX groups inside Pascal comments (the result would not be legal Pascal code anymore). Other TEX delirniters must be used; by default, PPP uses the square brackets ' [' and '1 '. Program fragments. PPP was taught the minimum amount of Pascal syntax that allows it to typeset Pascal code; it is thus not a syntax-checker. While some syntax errors (such as a missing end) will cause incorrect or unexpected output, some others (such as unbalanced parentheses) will be happily ignored. However, the package was designed for inserting illustrative pieces of code in textbooks, including incomplete programs. PPP has facilities for handling these, though it needs hints from the author as to what parts are missing. These hints basically consist in supplying -in a hidden form the important missing elements, so PPP knows how many groups to open and can then close them properly. your code, you can say \def\p@foo{{\i t fool} before your code and PPP will do the rest. At a low level, you can go and change anything you want, providing you know what you are doing and you first save PPP under a different name. Underlying principles The PPP environment pretty-prints the code in one pass: it reads the tokens, recognizes reserved words and constructs, and typesets the code accordingly, indenting the commands according to depth of grouping. Specifically, PPP relies on tail-recursion to read a list of tokens: one main command reads one or several tokens, processes them, then calls itself again to read and process subsequent tokens until it encounters a stop token; decides what to do for each token using a modified version of Jonathan Fine's \ F I N D macro; recognizes words as reserved by checking for the existence of a TEX command with the corresponding name and acts upon reserved words by executing this command; TUGboat, Volume 1 5 (1994), No. 3 -Proceedings of the 1994 Annual Meeting